.\"
.\" Copyright (C) 1994-2021 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of both the OpenPBS software ("OpenPBS")
.\" and the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" OpenPBS is free software. You can redistribute it and/or modify it under
.\" the terms of the GNU Affero General Public License as published by the
.\" Free Software Foundation, either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" OpenPBS is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" PBS Pro is commercially licensed software that shares a common core with
.\" the OpenPBS software.  For a copy of the commercial license terms and
.\" conditions, go to: (http://www.pbspro.com/agreement.html) or contact the
.\" Altair Legal Department.
.\"
.\" Altair's dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of OpenPBS and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair's trademarks, including but not limited to "PBS™",
.\" "OpenPBS®", "PBS Professional®", and "PBS Pro™" and Altair's logos is
.\" subject to Altair's trademark licensing policies.
.\"
.TH pbs_statjob 3B "15 November 2019" Local "PBS Professional"
.SH NAME
.B pbs_statjob 
\- get status of PBS batch jobs
.SH SYNOPSIS
#include <pbs_error.h>
.br
#include <pbs_ifl.h>
.sp
.nf
.B struct batch_status *
.B pbs_statjob(int connect, char *ID, struct attrl *output_attribs, 
.B \ \ \ \ \ \ \ \ \ \ \ \ char *extend)
.fi
.SH DESCRIPTION
Issues a batch request to get the status of a specified batch job, a
list of batch jobs, or the batch jobs at a queue or server.

Generates a 
.I Status Job 
(19) batch request and sends it to the server over the connection specified by 
.I connect.

You can query status of jobs, job arrays, subjobs, and ranges of subjobs.

Queries all specified jobs that the user is authorized to query.

.SH ARGUMENTS
.IP connect 8
Return value of 
.B pbs_connect().  
Specifies connection handle over which to send batch request to server.

.IP ID 8
Job ID, list of job IDs, queue, server, or null.  
.br
If 
.I ID 
is a null pointer or points to a null string, gets status of jobs at connected server. 
.br
Format for a job:
.br
.I <sequence number>.<server name>
.br
Format for a job array:
.br
.I <sequence number>[].<server name>
.br
Format for a subjob:
.br
.I <sequence number>[<index>].<server name>
.br
Format for a range of subjobs:
.br
.I <sequence number>[<index start>-<index end>].<server name>
.br
Format for a list of jobs: comma-separated list of job IDs in a single
string.  White space is ignored.  No limit on length:
.br
.I "<job ID>,<job ID>,<job ID>, ..."
.br
Format for a queue:
.br
.I <queue name>@<server name>
.br
Format for a server:
.br
.I <server name>
.br

.IP output_attribs 8
Pointer to a list of attributes to return.  If this list is null, all
attributes are returned.  Each attribute is described in an 
.I attrl
structure, defined in pbs_ifl.h as:
.nf
struct attrl {
        char         *name;
        char         *resource;
        char         *value;
        struct attrl *next;
};
.fi

.IP extend 8
Character string where you can specify limits or extensions of your
search.  Order of characters is not important.

.LP
.B Members of attrl Structure
.br
.IP name 8
Points to a string containing the name of the attribute.  

.IP resource 8
Points to a string containing the name of a resource.  Used only when
the specified attribute contains resource information.  Otherwise,
.I resource 
should be a null pointer.

.IP value 8
Points to a string containing the value of the attribute or resource.  

.IP next 8
Points to next attribute in list.  A null pointer terminates the list.

.SH QUERYING JOB ARRAYS AND SUBJOBS
You can query status of job arrays and their subjobs, or just the parent job arrays only.

To query status of job arrays and their subjobs, include the job array
IDs in the 
.I ID 
argument, and include the "t" character in the 
.I extend
argument.  The function returns the status of each parent job array
followed by status of each subjob in that job array.

To query status of one or more parent job arrays only, but not their
subjobs, include their job IDs in the 
.I ID 
argument, but do not include anything in the 
.I extend 
argument.

.SH QUERYING THE JOBS AT A QUEUE OR SERVER
To query status of all jobs at a queue, give the queue name in the 
.I ID 
argument.

To query status of all jobs at a server, give the server name in the
.I ID 
argument.  If you give a null ID argument, the function queries the
default server.

.SH EXTENDING YOUR QUERY
You can use the following characters in the extend parameter:
.IP "T, t" 8
Extends query to include subjobs.  Job arrays are not included.

.IP x 8
Extends query to include finished and moved jobs.
.LP
.B Querying Finished and Moved Jobs
.br
To get status for finished or moved jobs, as well as current jobs, add
an 'x' character to the 
.I extend 
parameter (set one character to be the 'x' character).  For example: 
.br
.I \ \ \ pbs_statjob ( ..., ..., <extend characters>) ...

Subjobs are not considered finished until the parent array job is finished.


.SH RETURN VALUES

For a single job, if the job can be queried, returns a pointer to a
.I batch_status 
structure containing the status of the specified job.
If the job cannot be queried, returns a NULL pointer, and 
.I pbs_errno 
is set to an error number indicating the reason the job could not be queried.

For a list of jobs, if any of the specified jobs can be queried,
returns a pointer to a 
.I batch_status 
structure containing the status
of all the queryable jobs.  If none of the jobs can be queried,
returns a NULL pointer, and 
.I pbs_errno 
is set to the error number that indicates the reason that the last
job in the list could not be queried.

For a queue, if the queue exists, returns a pointer to a 
.I batch_status
structure containing the status of all the queryable jobs in the
queue.  If the queue does not exist, returns a NULL pointer, and
.I pbs_errno 
is set to 
.I PBSE_UNKQUE (15018).  
If the queue exists but contains no queryable jobs, returns a NULL pointer, and 
.I pbs_errno 
is set to 
.I PBSE_NONE (0).

When querying a server, the connection to the server is already
established by 
.B pbs_connect().  
If there are jobs at the server, returns a pointer to a 
.I batch_status 
structure containing the status of all the queryable jobs at the
server.  If the server does not contain any queryable jobs, returns a
NULL pointer, and 
.I pbs_errno 
is set to 
.I PBSE_NONE (0).  

.B The batch_status Structure 
.br 
The 
.I batch_status 
structure is defined in pbs_ifl.h as
.nf 
struct batch_status {
        struct batch_status *next;
        char                *name;
        struct attrl        *attribs;
        char                *text;
}

.SH CLEANUP
You must free the list of 
.I batch_status 
structures when no longer needed, by calling 
.B pbs_statfree().

.SH SEE ALSO
qstat(1B), pbs_connect(3B), pbs_statfree(3B)
